Basic4GL standalone exes

Basic4GL can take any Basic4GL program and create an executable file.
This program can run on its own, and does not require Basic4GL to be installed.

Basic4GL creates the executable uses a process called "binding". Your program code is combined with the Basic4GL compiler and virtual machine into a single exe file. When the exe file runs, the Basic4GL compiler compiles your program, and then the virtual machine runs it.

Quick start

To create a stand-alone executable:

Start Basic4GL
Open your Basic4GL program (Program|Open...)
Ensure it compiles and runs properly
Click "Program" on the main menu then "Create Standalone .exe..."

The create standalone exe options dialog box will appear. You can now configure how your exe will be created.
It is recommended you at least set the filename, so you can choose a directory where you will be able to find the file once it's created (otherwise by default the file will be created in the same directory as the original Basic4GL source file.).

When you are ready, click "Create Program" to generate your exe file.

This will create a single .exe file. To run the file, navigate to it on your hard drive and double click it. Note: If the program requires other files be present e.g. images, data files e.t.c, it may not run correctly if it cannot find them. See the "Embedded files" section below for a method of including images and other files directly into your .exe file, so that you do not have to distribute them separately.

Create standalone exe options

There are several ways you can configure how the program will work, and how and where it will be created. These are divided into several tabbed pages in the "Create standalone exe" dialog box.

"Program" tab

This allows you to specify the output filename, and the window title.
By default the name of the Basic4GL program is used (i.e. "MyGame.gb" will create a file "MyGame.exe", with a window title "MyGame"). If the Basic4GL program hasn't been saved to disk yet, it will default to "MyProgram.exe" (filename) and "MyProgram" (display name).
The display name is also shown when you Alt-Tab between applications.

"Options" tab

This allows you to specify what will happen when the program encounters a runtime error, or reaches the end of the program (or an "end" command). There are two options:

When the program finishes it should

Some programs keep on executing until the user quits (presses Escape or closes the window).
Others will perform an action, display the results and then finish.

Here you can specify whether it is appropriate to close the program down immediately, or wait for a keypress (to give the user time to look at the results on the screen) before closing. You can also choose to keep the window open until the user closes it by clicking on the close button. (This option does not apply when in full screen mode.)

If a runtime error occurs the program should

Typical runtime errors include:

Reading off the end of an array
Trying to access a null pointer
Trying to access a variable that hasn't been DIMmed yet

If an error like this occurs the Basic4GL program cannot continue, and must stop. In Basic4GL it would position the cursor where the problem is and give a description of what went wrong. But in a standalone application you cannot do this (and probably wouldn't want to).
So here you can specify what to do instead, either display a full error description with line number and column, or display a general error message ("An error has occured"), or just close the application.

"Esc" or Closing Window quits

This checkbox determines whether the program will close immediately when someone presses the Escape key, or closes the program window (in windowed mode).
By default (tick box is ticked) Basic4GL halts the program, cleans up any resources used (e.g. textures or file handles) and closes the program.

Sometimes you may not want Basic4GL to quit immediately.
Usually this is when you want to perform some clean-up before the user exits, for example, saving the player's position in a game, or saving the user's configuration settings to a file, or just asking "are you sure?".
In this case you can clear the tickbox and the program will not close automatically.
You must add code to your program to allow the player to quit! Otherwise they will have to kill the program with task manager which isn't very friendly.
The program will quit when either:

The program reaches the end, or
An "end" instruction is encountered.

Example 1:

printr "Press Q to quit"
while lcase$ (inkey$ ()) <> "q"

    ' Do something
    ' ...
                  
wend

' Cleanup 
' ...

printr "Goodbye"

Example 2:

printr "Press Q to quit"
while true
    
    ' Do something
    ' ...
    
    if lcase$ (inkey$ ()) = "q" then

        ' Cleanup 
        ' ...

        printr "Goodbye"        
        end
    endif
wend

Basic4GL will simulate a VK_ESCAPE keypress if the user clicks the close button on the window (in windowed mode).
You can detect this as follows:

if InScanKey () = VK_ESCAPE then
    
    ' User wants to quit
    ' ...

endif

"Screen Mode" tab

Here you can choose the screen mode that the program will run in.
Currently there is no option for letting the user choose. This may change in a later version of Basic4GL.

"Embedded Files" tab

Many programs require extra files in order to run properly, such as textures and data files. If the program cannot find them, it won't run correctly and may not run at all.
Normally this means you have to distribute all these files separately, either in a compressed archive (like a zip file) or using some sort of installer.

Basic4GL has an "Embedded Files" mechanism which can simplify this by storing the support files directly into the executable file itself. These files load automatically whenever the program loads in a file with the same filename, for example using LoadTexture, LoadSound or OpenFileRead, so you don't need to change your program to make it work.
If the file isn't found inside the executable, the program will attempt to load it from disk as per normal.

By embedding all your textures, sound files and other support files you can boil your program down to a single exe file that can be distributed by itself.

Default embedded files

You will often find that Basic4GL has already made a guess at the files that the program uses (it does this by scanning through the program for strings that match up to filenames on your drive). In this case the files will already be entered into the embedded files list.
For example, if you create a standalone exe from "AsteroidDemo2.gb" from the Programs folder you will see that it has guessed all the files that the program requires.)
There are some situations where Basic4GL cannot guess all the files that the program will access.
For example:

dim path$, filename$, tex
path$ = "textures"
filename$ = "00001.jpg"
tex = LoadTexture (path$ + "\" + filename$)

Will load a texture called "textures\00001.jpg". Basic4GL will not detect this however (as it sees "textures" and "00001.jpg" separately.) If you didn't want to distribute the "textures\00001.jpg" file along with the standalone exe, you would need to add it manually to the embedded files list.

Adding embedded files

Simply click the "Add..." button, browse to the files you want to include, select them and click "Open". Do this as many times as necessary.
Note: Simply adding a file doesn't mean that the program will use it. You still have to write the Basic4GL code to load and use the file. Otherwise it will simply sit in the exe and waste space!

Deleting embedded files

Sometimes you don't want to use the embedded files mechanism.
For example, you may want to distribute an image separately so that the user can edit it and customise their game.
Also embedded files are loaded into memory as soon as the program starts (even if they aren't used), and will use this memory until the program exits. If you have a large number of data files you may want to load them in as they are required and then free them up once you are finished with them. In this case distributing the files separately might be a better idea.

To remove files from the embedded files list, simply select them and click "Remove".

"UPX compression" tab

Note: UPX (the "Ultimate Packer for eXecutables") is in no way associated with Basic4GL or it's authors.

UPX is a very useful utility that compresses executable files (as well as DLLs and other executable formats). Using UPX, you can compress a Basic4GL standalone exe from 1.1 megabytes down to a much more managable and distributable 350K.

To make it even easier, you can configure Basic4GL to invoke UPX for you immediately after it creates your standalone exe. UPX is not installed with Basic4GL so you will first have to go to the UPX homepage and download and unzip it yourself.
Once that's done, you will need to tell Basic4GL where it is on your hard drive. Ensure the "Compress program with UPX" tickbox is ticked, then click the browse button and select the UPX.exe file on your hard drive.
Basic4GL will now use UPX to compress the executable once created.

About the exe file

You should be aware that:

There are no extra DLLs or support files that need to be distributed (besides any files that the program needs to load that aren't embedded into the executable).
The program should run on any Windows PC with a proper OpenGL implementation. I.e any PC that can run Basic4GL should be able to run your standalone exe.
The default font texture is automatically included into the executable.
Standalone executable files will not run any faster than programs running in Basic4GL. This is because Basic4GL does not compile your programs to true machine code.
The file that it creates contains the Basic4GL compiler, the Basic4GL virtual machine and a copy of your Basic4GL program. When you double click the executable, it compiles up the internal Basic4GL code and runs it on the virtual machine, in exactly the same way as the Basic4GL application does.
Your original Basic4GL program isn't hidden. It's still there inside the executable.
This will be less of an issue in future versions of Basic4GL where the standalone exe will contain only the virtual machine and the program compiled into virtual machine op codes. But for now, your source code is right there inside the exe.
Standalone executables are relatively large.
A hello world program (print "Hello world") will generate a 1.1 meg executable (350K if you compress it with UPX).
This is because it contains the full compiler, virtual machine, and libraries (the image loading library by itself compiles to about 600K). Even if they aren't used, they are there.

Licensing issues

So long as you wrote the original Basic4GL program, you are free to distribute any standalone files that you generate from it as you see fit, even sell them. However there are some restrictions (e.g. to protect the Basic4GL part from being extracted and sold for example).

Refer to the "Standalone Executables" section of the Basic4GL License (License.txt), for more information.